From 701daf2b0565047e41aa4691c4007eaeb32416a5 Mon Sep 17 00:00:00 2001 From: Martin Renold Date: Sat, 16 Nov 2013 01:25:27 +0100 Subject: [PATCH] gdk: Document event compression better Advise against using GDK_POINTER_MOTION_HINT_MASK. Add pointers to gdk_window_set_event_compression() to the documentation. --- gdk/gdkdevice.c | 4 ++++ gdk/gdktypes.h | 23 +++++++++++++---------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c index 6355073b2c..d41380430d 100644 --- a/gdk/gdkdevice.c +++ b/gdk/gdkdevice.c @@ -593,6 +593,10 @@ gdk_device_get_window_at_position (GdkDevice *device, * be returned. (This is not distinguishable from the case where * motion history is supported and no events were found.) * + * Note that there is also gdk_window_set_event_compression() to get + * more motion events delivered directly, independent of the windowing + * system. + * * Return value: %TRUE if the windowing system supports motion history and * at least one event was found. **/ diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index d821251cac..1ca617e961 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -328,7 +328,7 @@ typedef enum * GdkEventMask: * @GDK_EXPOSURE_MASK: receive expose events * @GDK_POINTER_MOTION_MASK: receive all pointer motion events - * @GDK_POINTER_MOTION_HINT_MASK: see the explanation above + * @GDK_POINTER_MOTION_HINT_MASK: deprecated. see the explanation above * @GDK_BUTTON_MOTION_MASK: receive pointer motion events while any button is pressed * @GDK_BUTTON1_MOTION_MASK: receive pointer motion events while 1 button is pressed * @GDK_BUTTON2_MOTION_MASK: receive pointer motion events while 2 button is pressed @@ -356,15 +356,18 @@ typedef enum * Most of these masks map onto one or more of the #GdkEventType event types * above. * - * %GDK_POINTER_MOTION_HINT_MASK is a special mask which is used to reduce the - * number of %GDK_MOTION_NOTIFY events received. Normally a %GDK_MOTION_NOTIFY - * event is received each time the mouse moves. However, if the application - * spends a lot of time processing the event (updating the display, for example), - * it can lag behind the position of the mouse. When using - * %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will be sent, - * some of which are marked as a hint (the is_hint member is %TRUE). - * To receive more motion events after a motion hint event, the application - * needs to asks for more, by calling gdk_event_request_motions(). + * %GDK_POINTER_MOTION_HINT_MASK is deprecated. It is a special mask + * to reduce the number of %GDK_MOTION_NOTIFY events received. When using + * %GDK_POINTER_MOTION_HINT_MASK, fewer %GDK_MOTION_NOTIFY events will + * be sent, some of which are marked as a hint (the is_hint member is + * %TRUE). To receive more motion events after a motion hint event, + * the application needs to asks for more, by calling + * gdk_event_request_motions(). + * + * Since GTK 3.8, motion events are already compressed by default, independent + * of this mechanism. This compression can be disabled with + * gdk_window_set_event_compression(). See the documentation of that function + * for details. * * If %GDK_TOUCH_MASK is enabled, the window will receive touch events * from touch-enabled devices. Those will come as sequences of #GdkEventTouch -- 2.30.2